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About This Manual 


Purpose of this Manual 


This manual describes the installation of soL Connector on client (first tier), data 
broker (second tier) and data driver (third tier) operating systems. soL Connector 
installations must be carefully planned to insure success. ThiS manual provides 
directions and guidelines for the multiple tiers which must be configured for an SQL 
Connector installation. 


Intended Audience 


This document is intended for system administrators who will be installing SQL 
Connector. A working knowledge of J ava, ODBC, J DBC, database systems, operating 
systems and networking is required to install and test soL Connector. 


Structure of this Manual 


This manual consists of chapters which describe how to install soL Connector. There 
are separate chapters for each tier in the installation process. 


Associated Documents 


The soL Connector document set contains these manuals: 
* sol Connector Overview 
* soL Connector Installation Guide 
* sol Connector Administration Guide 
* sor Connector SQL Grammar Manual 
* soL Connector ODBC Programmer’s Guide 
* sol Connector | DBC Programmer's Guide 


Conventions 


When there are differences in commands, examples, or syntax between operating 
systems, the following abbreviations are used: 


Abbreviation Meaning 
NetWare the Novell NetWare operating system 
Windows the Microsoft Windows 95/98/NT operating systems 
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1.1 Components 


SQL Connector is a Data Request Broker that provides a multiple-tier, multiple 
database enterprise environment for connecting ODBC (Open Database Connectivity) 
applications and J DBC (J ava Database Connectivity) applications between client 
systems and database servers. 


SQL Connector includes Client, Data Broker and Data Driver components. These 
components can reside on the same or different systems within a network. The client 
components support the connection of soL Connector to end user applications or 
application development tools that use ODBC or J DBC. The Data Broker components 
support client connectivity over a network, query parsing, optimization and 
distribution. The Data Broker components also support database administration for 
maintaining the soL Connector Data Sources. 


The Data Driver components support local or remote connectivity to physical 
databases. These components are summarized in the following tables. Note that flat 
files can be used transparently as a precursor to using a physical database. 


















































Component Name Component Functionality Usage 
Windows 95/98/NT Client Components 

SQL C-ODBC Microsoft® ODBC”" Driver API optional 
sor C-) DBC J avaSoft™ J ava” SQL classes optional 
NetWare Data Broker Components 

soL C-DSA Data Source Administrator required? 
sor C-DRB Data Request Broker required 
Local and Remote Data Driver Components 

SQL C-ORA-DD Oracle® Database Connection optional 
sor C-ODBC-DD ODBC Database Connection optional 





a. Required for database administrators, not required for developers or users. 


1.2 Architecture 


The soL Connector architecture includes the Client, Data Broker and Data Driver 
components listed in the above table. The architecture is designed for maximum 
flexibility in meeting the needs of enterprise wide application development and 
deployment. The components have been modularized so that they can be installed on 
multiple tiers within an enterprise network. 
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Note: 


Local Data Drivers execute on the same system as the Data Broker. Renote Data 
Drivers execute on systems that are networked to the Data Broker system. This 
version of SQL Connector supports the following local and remote Data Drivers: 





System | Oracle | ODBC 
Local Remote 








Novell 
Netware 

















The complete component architecuture is shown below: 


SQL Connector Components 
Windows 




















Client Dictionary Manager and SOL ODBC Driver DEC Driver 
System su C- MGR and wgl C- SH agl C- ODAC eo. C- JDBC 
__ Network | may 
Dictionary - soLC-DICT /) 
Netware Data Request Broker - sq.C-DRB / 







Data Broker 


| aE- | 
Local on acta 


Data Driver 





Eta, Mi ig 
FILES 


Pebwork 
Windows NT 
Remote 
Data 


Dir ver 





ACCESS 


The ODBC Client Component and the ODBC Data Driver are separate modules. 
The ODBC Client Component is an interface between end-user client applications 
and the Data Broker. The ODBC Data Driver is a data source (like Oracle, 
Sybase, etc.) for the Data Broker. Multiple ODBC data sources can connect 
through the Data Broker into a single ODBC client application. 





SaL | Database ¿Network 
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1.3 Prerequisites 


1.3.1 Client Components 


The client requires: 
1. Windows 95/98/NT client operating system (includes ODBC-32). 


2. ForJava/) DBC application development, J ava Development Kit (J DK) 1.1.8 
or higher, available at: http:/Awww.javasoft.com/products/jdk/1.1/. 


3. For ODBC application development, ODBC-32 2.5 or higher. 





1.3.2 Data Broker and Local Data Driver Components 
The Data Broker requires: 
e NetWare5.1. 
e Administration access for installation. 


+ NetWare modules dsapi.nim, netdb.nim, nIsapi.nlm, nIsIsp.nlm and Isapi.nlm 
must be loaded. 


e NetWare Oracle module oci7stub.nlm must be loaded. 





The following local Data Drivers are supported on NetWare 5.1: 
e Oracle8.1.5 


1.3.3 Remote Data Driver Components 


The Data Drivers are available for use by soL Connector in connecting to physical 


databases. These Data Drivers require the versions of operating systems listed in the 
following table 





System | ODBC 








Windows | 2.5 or 
NT 4.0 | higher 














Note: The version numbers listed in the above table represent the highest version 
numbers of the databases that have been verified for proper operation with SQL 
Connector. Lower versions of the databases may function correctly ifthe database 


vendor has maintained backwards compatibility. Contact Customer Support for 
additional information. 
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Broker Installation Procedure 





2.1 Introduction 


The soL Connector architecture includes Client, Data Broker and Data Driver 
components as discussed in the previous chapter. These components can be installed 
on multiple systems within an enterprise network. 


ThesaL Connector Data Broker is a set of programs that respond to data requests 
from soL Connector Clients and send data requests to soL Connector Local and 
Remote Data Drivers. The soL Connector Local and Remote Data Drivers provide 
database access to local and remote databases 


The installation procedure is designed for a multiple tier configuration. The Data 
Broker and Local Data Drivers are typically installed on a single Netware server 
(middle tier). The Client components can be installed on multiple end-user systems 
(first tier), and the Remote Data Driver can be installed on multiple Windows NT 
database servers (third tier). 

When Netware is installed, the soL Connector Data Broker and Local Data Driver files 
are placed in the directory SYS:SYSTEM\SQLC, and the soL Connector Client and 
Remote Data Driver installation files are placed in the directory SYS: PUBLIC\SQLC. 
The puBLIc copies can be used multiple times as needed to install Client components 
and Remote Driver components on other systems. 

Theremainder of this chapter discusses configuration, administration and verification 
procedures for the Data Broker. 

The following chapters discuss installing the Client and Data Driver components on 
other systems (first and third tiers). 


2.2 Configuration Procedure 
When Netwareis installed, the Data Broker is automatically installed and configured. 
The installation has performed these actions: 
e Create and enable soL Connector startup and shutdown files. 
e Edit the network file sys: etc\services. 


e Extends the NDS User Schema to support SQL Connector environment 
variables. See “NetWare Administration Extensions” for additional 
information. 


Note: The Internet hosts file must be manually edited. See “Internet Host Names and 
Addresses” for additional information. 
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2.2.1 Startup Procedure 


The configuration procedure automatically creates a startup file sqlc.ncf and edits 
autoexec.ncf to call the startup file. The startup file has the following commands: 


search add SYS:\SYSTEM\SQLC 
load SQLCMON <username> <password> 
load VTXNETD -p1958 -n 








load SQLCODBC 





Note: The NetWare modules dsapi.nim, Isapi.nlm, netdb.nIm, nls.nlm, and nlsapi.nlm 
must be loaded prior to loading sqicmon.nim. 


2.2.2 Shutdown Procedure 


The configuration procedure automatically creates a shutdown file sqlckill.ncf. 
The shutdown file has the following commands: 


unload sqlcodbc 


unload vtxodbc 


load vtxkill -p1958 <server name> 


unload vtx16 
pause 

unload vtxnetd 
unload sqlcmon 


This shutdown file will be automatically called when soL Connector is shutdown by 
executing the following commands. 


load SQLCADM 


SQLCADM> shutdown 


2.2.3 Internet Host Names and Addresses 


ThesoL Connector components (Client, Broker, Data Drivers) use! nternet host names 
and/or Internet Protocol (IP) addresses (nnn. nnn.nnn.nnn) for communications. All of 
the components will work with addresses used in place of node names. Node names 
are typically designated system-wide using a naming service such as DNS (Domain 
Naming Service). If DNS is not enabled, then the following system files must be edited 
to map host names and IP addresses for the soL Connector components to 


communicate. 





Operating System 


File Name and Location 























Windows NT $SYSTEM_ROOT%\system32\drivers\etc\hosts 
Windows 95/98 SWINDIR%\hosts 
Netware 5.x SYS:ETC\HOSTS 

















2.2.4 DataDrive Setup 


The system file sys: etc/services is automatically edited to include the Data Driver 
TCP/IP service name and port number. The default port numbers are: 


ODBC: sqliodbcserv 8106/tcp 
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See Chapter 4 for more information on setting Data Driver TCP/IP port numbers. 


2.3 Administration 


Note: 


The following programs are used by the soL Connector Data Request Broker: 





VTXNETD.NLM 
VTX16.NLM 
VTXODBC.NLM 
VTXKILL.NLM 
SOLCMON. NLM 
SOLCODBC.NLM 
SOLC . NLM 
SOLCADM. NLM 


VTXNETD.NLM is a multi-threaded network listener that processes database requests 
from ODBC and J DBC dient applications. The listener will assign a unique thread to 
each client application. All client applications must use a TCP/IP port number which 
matches the "p" argument specified when vrxnETD.NLM iS loaded. The ODBC 
Programmer's Guide and the] DBC Programmer's Guide provide additional 
information on setting the port number used by the client application. 


VTX16.NLM is a multi-threaded request processor that translates between network 
requests and database requests, and provides data buffering over the network. For 
example, multiple (small) rows returned by an SQL SELECT statement will be 
combined into a single (large) buffer for transmission over the network. 


VTXODBC.NLM iS a network processor that handles NetWare clients that make ODBC 
requests, such as those from the Netscape Enterprise Server. 


VTXKILL.NLM İS a utility for stopping VTXNETD . NLM. 






































SOLCMON . NLM iS a database monitor that assigns each client thread to its own database 
broker and monitors the activity of each thread. The database broker consists of a 
database engine that connects to one or more local or remote physical databases and 
includes an internal memory pool for each database engine. 


SOLCODBC . NLM İS a processor that connects network ODBC requests to the database 
engine. 





soLc.NLM is a database engine that provides the physical database connections and 
processes the physical database requests (SQL SELECT, INSERT, UPDATE, DELETE, 
etc.) from each client thread. 








SQLCADM.NLM İS a database engine administrator which provides control, logging and 
status information for each database engine in the database monitor. See Appendix A 
for information about running soLcapM.NLM. 


The shutdown option of soLcanm will unload SQLCMON . NLM and VTXNETD .NLM. 





2.4 Verification 


After the soL Connector Data Broker and local Data Driver components are installed 
and loaded (see following chapters), they can be tested by creating Data Sources and 
using the odbcping, odbcjoin, jdbcping and jdbcjoin programs, which are documented in 
the ODBC Programmes Guideand the] DBC Programmer's Guide. These programs 
can be found on SYS: PUBLIC\SQLC\ SAMPLES. 
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Client Installation 





3.1 Introduction 


ThesaL Connector ODBC Driver (SQL C-ODBC)andthesaL Connector J DBC Driver 
(saL C-J DBC) are Client components that connect tothesaL Connector Data Request 
Broker (SQL C-DRB). soL C-J DBC requires J avasoft J DK or J RE 1.1.8 or higher (see 
Chapter 1 for additional information). 


ThesoL Connector NetWare Administrator Extensions allow a NetWare 
Administrator to set soL Connector environment variables. 


3.2 Procedure 


For ODBC application development on Windows, the following steps are necessary: 
* soL C-ODBC driver installation 

For ODBC application deployment on Windows, the following steps are necessary: 
+ soL C-ODBC driver installation 

For J DBC application devd opment on Windows, the following steps are necessary: 


e Java Development Kit installation (download from www.javasoft.com) 
e sol C-J DBC driver installation 





For J DBC application deployment on Windows, the following steps are necessary: 


e J ave Runtime installation (download from www.javasoft.com) 
e sol C-] DBC driver installation 





3.2.1 ODBC Driver Installation 


The soL C-ODBC installation procedure can be started by executing the setup file on 
the software distribution path. The file can be executed by double-clicking the file 
name using the Windows Explorer or by browsing for the file using the Start ->Run 
Menu command. The setup file has the following location: 


SYS: PUBLIC\SQLC\client \ODBC\disk1\setup.exe 
The installation procedure has no options. The Destination Directory location is: 
C:\Program Files\SQLC\ODBC 


Files are copied from the installation directory to the system directory and to the 
Destination Directory, and ODBC entries are made in the system registry. 


The following files are installed in the windows NT system32 directory: 
tod32.d11: SQL Connector ODBC driver 


vtx3.dll: Communications layer between ODBC and network 
The soL C-ODBC Driver can then be used in client ODBC applications. See the 
ODBC Programmer's Guide for additional information. 


Readme and uninstall information is copied to the Destination Directory. 
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3.2.2 JDBC Driver Installation 


3.2.2.1 Windows 


The soL C-J DBC installation procedure can be started by executing the setup file on 
the software distribution path. The file can be executed by double-clicking the file 
name using the Windows Explorer or by browsing for the file using the Start - > Run 
Menu command. The setup file has the following location: 

SYS: PUBLIC\SQLC\client\JDBC\setup.exe 


The first prompt is the Destination Directory. The default location is: 


C:\Program Files\SQLC\JDBC 
The destination directory can be changed by browsing for an alternate location, which 
will be created if it does not exist. 
The installation procedure will create a J AR file in the Destination Directory, e.g.: 
sqlcjdbc.jar 
This jar file should be placed in the] ava CLASSPATH so it can be accessed by J ava 
programs such as third party application development environments that will usethe 


SQL Connector J DBC classes. Seethe J DBC Programmer’s Guide for additonal 
information. 


Uninstall information is also placed in the same directory. 


3.2.2.2 NetWare 


The same jar file can be copied to a NetWare system for executing J ava J DBC 
applications or browser applets. The file should be copied to sys: \JAVA\CLASSES, and 
the NetWare cLasspatu should be modified to include the jar file. See the) DBC 
Programmer's Guide for additional information. 





3.2.3 NetWare Administration Extensions 


3.2.3.1 Installation 


The NetWare Administration Extensions installation procedure can be started by 
executing the setup file on the software distribution path. The file can be executed by 
double-dicking the file name using the Windows Explorer or by browsing for the file 
using the Start | Run Menu command. The setup file has the following location: 


SYS: PUBLIC\SQLC\NetWare\NDSAdmin\disk1\setup.exe 


<SOFTWARE> is the distribution path specified during the first phase of the installation 
(see previous chapter). The Destination Directory location for uninstall information is: 





C:\Program Files\SQLC\NDS 


The installation procedure prompts for the location of the NetWare 5.x Administration 
program and then copies files to the Administration directory and make registry 
entries for NDS Snapins. The following files are installed in the Admininistration 
directory: 


sqicndserv.dll 
snapins\sqlcuserenv.dll 


3.2.3.2 Usage 


User Extension 
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After the installation, the NDS User Object has been extended as shown in the 
following figure (double-click on a user name in NDS Admin to see this extension). 








[tiara E" 


DRA SCOTT SCOTTNGER 
55_TRACE YES 











3.2.4 Verification 


3.2.4.1 ODBC Driver Verification 


The soL C-ODBC driver can be tested using a sample program odbcping that is 
discussed in the ODBC Programmer's Guide The sample program files arein the 
software distribution path as follows: 


SYS:PUBLIC\SQLC\Samples\Windows\odbc\odbcping.c 
SYS:PUBLIC\SQLC\Samples\Windows\odbc\odbcping.exe 
SYS:PUBLIC\SQLC\Samples\NetWare\odbc\odbcping.c 
SYS:PUBLIC\SQLC\Samples\NetWare\odbc\odbcping.nlm 


The odbcping program will attempt an ODBC connection from a Netware or Windows 
client to an soL Connector Data Source through a Data Broker running on a network 
server. See the ODBC Programmer’s Guide for more details. 


3.2.4.2 JDBC Driver Verification 


The soL C-J DBC driver can be tested using a sample program jdbcping that is 
discussed in the] DBC Programmer's Guide The sample program files are in the 
software distribution path as follows: 


SYS:PUBLIC\SQLC\Samples\Windows\jdbc\jdbcping.java 
SYS:PUBLIC\SQLC\Samples\Windows\jdbc\jdbcping.class 
SYS:PUBLIC\SQLC\Samples\NetWare\jdbc\jdbcping.java 
SYS:PUBLIC\SQLC\Samples\NetWare\jdbc\jdbcping.class 


The Windows and NetWare] ava programs are identical. The jabcping program will 
attempt a J DBC connection from a Netware or Windows client to an soL Connector 
Data Source through a Data Broker running on a network server. See the] DBC 
Programmer's Guide for more details. 
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Remote Data Driver Installation 





4.1 Configuration Information 


The soL Connector Remote Data Drivers are Internet server programs that run on 
remote Windows NT systems. Each remote system has an Internet server process that 
listens for incoming requests from the soL Connector Data Broker and routes the 
requests tothe appropriate Data Driver, which connects tothe physical database. The 
SQL Connector Data Request Broker and thesoL Connector Remote Data Drivers 
communicate using two pieces of information: 


1. A designated TCP/IP port number or TCP/IP named service that corresponds with 
a designated port number. The service name or port number must match on the 
Broker (client) and Driver (server) sides of the connection. The soL Connector 
Data Broker will send out TCP/IP requests using this service name or port number. 


2. Aninternal remote Data Source. This Data Source stores the names of the remote 
physical database tables that have been chosen by the user of the Data Broker. The 
database table names must match on the Broker (client) and Driver (server) sides 
of the connection. 


4.2 Windows NT Remote Data Driver Installation 


4.2.1 Introduction 


The Broker and Data Drivers communicate using a TCP/IP process that emulates the 
standard | nternet service and configuration files (inetd and inetd.conf). Sincethere 
is no standard inetd server process on Windows NT systems, SQL Connector provides a 
substitute process named sqlc_inetd.exe and a substitute configuration file named 
sqlc_inetd.conf (the NT services file is not used). 


This service (sqlc_inetd) runs on the same system as the Data Drivers. It listens for 
Broker service requests on the TCP ports associated with each of the services listed in 
its configuration file (sqlc_inetd.conf). When a request arrives, sqlc_inetd 
executes the server program associated with the service. The configuration file is as 
follows: 


# Used by sqlc_inetd.exe to connect a broker to a database driver 
# Note that sqlc_inetd (SQL Connector Listener service) 

# must be restarted after this file is changed. 

# Port_number database_driver 

8106 ODBC\sqlcserver_odbc.exe 


The pathname of the Data Driver must be relative to the pathname of the server 
process (sqlc_inetd.exe). If the Data Driver is installed using a different relative 
pathname, then the above configuration file must be edited accordingly. 
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4.2.2 Database Support 


The following remote Data Driver is currently available for Windows NT systems. 
Please contact Customer Support for an updated list. 


+ ODBC 2.5 or higher 


Theremote Data Driver receives requests through the! nternet server process (Service 
name is SQLC-server Listener, program name is sqic_inetd.exe) that listens for 
incoming requests from the soL Connector Data Request Broker and routes the 
requests to the physical database. The Internet server process may be started 
manually at any time or automatically when the system is booted. The installation 
procedure for each Data Driver will copy files to the installation directory and create 
registry entries. Each installation procedure will then inquire about the startup 
options. 


The Data Driver installation procedures may be run by any user who has read/write 
access to the installation directory. The Internet server process must be started or 
stopped by a user with Administrator privilege. 


4.2.3 Procedure 


The installation procedure can be started by executing the setup file on the software 
distribution path (see previous chapter). Thefile can be executed by double-clicking 
the file name using the Windows Explorer or by browsing for the file using the Start - 
> Run Menu command. The installation procedures use the following setup files and 
default folder: 





Database Program Default Folder on System Disk 








ODBC 





\Drivers\NT\0DBC- \Program Files\SQLC\Drivers\ODBC 
OUT\disk1\setup.exe 














The installation procedure will first prompt for the destination folder. The default 
location may be changed by browsing for another folder, which will be created if it does 
not exist. 


After the files are copied, there will be a prompt for the startup choices for the NT 
service. The choices are: 

Automatic - restarts when the system is booted 

Manual - start from Services applet in Control Panel 


The default choice is Automatic. 


The last prompt is a choice to view the readme.txt file. After the last prompt, the 
installation procedure is finished. 


The Windows NT services file should be checked to insure there are no conflicts with 
the TCP/IP port numbers defined in the sqlc_inetd.conf. If there are conflicts, then 
the port numbers in sqlc_inetd.conf should be changed to eliminate the conflicts. 
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4.2.4 Verification 


The installation may be verified by starting the soL Connector Listener service. The 
Service I con in the Control Panel can be used to check the status of the service. The 
Data Driver is functioning correctly when the NT service can be started. 


The sat Connector Listener service can only be started by a user with Administrator 
privileges. If the privileges are not present, the error message is: 


SQLC-server Listener - Start 
Could not start the SQLC-server Listener service on \\<node>. 
Error 0005: Access is denied. 





If this error occurs, then try again as a user with Administrator privilege. 


A Windows NT Data Driver is used whenever thesoL Connector Data Request Broker 
attempts a connection to a remote Data Driver on NT. 
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NetWare Administration 





A.1 Overview 


SQLCADM.NLM iS a database engine administrator which provides control, logging and 
status information for each database engine that is executing in the database monitor. 
After loading soLcApM. NLM, a list of commands can be obtained by typing: 


> help 
The output is: 


Commands are: 





Status -- Display overall status of SQL Connector 

Purge -- Kill non-connected SQL Connector engines 

Shutdown -- Shutdown SQL Connector 

Engine first incr max -- Set SQL Connector engine parameters 
initial -- number of engines on startup 
incr -- number of engines to start when non-available 
max -- max number to run concurrently 

Logging {on|off} -- Turn logging on or off 

Save -- Persist settings 

Restore -- Restore settings from the persistence file 

SetEnv name value -- Set environment variable 

GetEnv name -- Display environment variable 

Help -- Display this text 

Exit -- To exit program 





A.2 Command Information 





A.2.1 Status 


Command format: status 


The status command will display information about SQLCMON. This includes: 


Number of free SQL Connector engines 
Number of SQL Connector engines initially created 
Number of SQL Connector engines per allocation cycle 


Maximum number of simultaneous SQL Connector engines 
Number of SQL Connector engines in use 


Size of the initial SQL Connector engine memory pool 
Size of additional SQL Connector engine memory pools 
Number of additional SQL Connector engine memory pools 
Maximum amount of memory per SQL Connector engine 
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A.2.2 Purge 
Command format: Purge 


The purge command causes sor.cmon to kill and deassign sorc engines. 


A.2.3 Shutdown 
Command format: shutdown 


The Shutdown command performs a purge and then causes soLcmon to exit. It will also 
cause soLcapm to exit (since sgLcapm can not commuiuncate with soLcmon once it shuts 
down). 


A.2.4 Engine 


Command format: Engine first incr max 





The Engine command controls the creation of soLc engines. The first parameter is 
the number of soLc engines that soLcmon will create when it first starts. The incr 
parameter is the number of soLc engines to start whenever there are not any available 
and one is required. The max parameter is the maximum number of soc engines that 
can be running at any time. 


A.2.5 Logging 
Command format: Logging on Or Logging off 


The Logging command turns on or off event logging. soLcmon will log key events to the 
log file soLcMon. Loc. At the time an event is logged, it is also displayed on the console. 


A.2.6 SetEnv 


Command format: SetEnv name value 





The SetEnv command sets environment variables for soLcmon. The name is case 
sensitive and the value is an uninterpreted string (no escape character processing). 
Environment variables are discussed in the SQL Grammar Manual. The environment 
variables become global values for all client applications. 


In particular, most client application development environments use double quotes 
around table names and column names. Toinform soLc engines about this behavior, 
the following command can be used: 

setenv SS_QUOTED_NAMES yes 














A.2.7 GetEnv 


Command form: GetEnv name 





The GetE nv command displays the environment value associated with name. This 
value is set with the SetEnv command. The name variable is case insensitive. 
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A.2.8 Save 
Command form: save 


The Save command persists the current parameter and environment toa data file. The 
data file is read when soLcmon starts to initialize the internal state of soLcmon. 


A.2.9 Restore 
Command form: Restore 


The Restore command resets the state of soLcmon parameters and environment 
variables to the values that are saved in the persistent data file by the Save command. 


A.2.10 Help 
Command form: Help 


The Help command provides a limited explanation of all of the commands available to 
SQLCADM. 


A.2.11 Exit 


Command form: Exit 





The Exit command causes soLcapm to terminate. 
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